home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / cutils.arc / RTNS.DOC < prev    next >
Text File  |  1985-08-30  |  15KB  |  465 lines
  1.  
  2.  
  3.  
  4.  
  5.                                OPERATOR'S MANUAL
  6.  
  7.                       11:11 C and Assembler Library  V1.0
  8.  
  9.                                  by Jon Wesener
  10.  
  11.                    (C)Copyright- Beyond System Control, 1985
  12.  
  13.  
  14.            This Software was written as a quick access to System
  15.         Resources and often needed routines.
  16.  
  17.                                                                         0- 1
  18.                                Table of Contents
  19.  
  20.         Sect 1: FILE I/O
  21.  
  22.         fcreate .............................................   1- 1
  23.         fopen ...............................................   1- 1
  24.         fclose ..............................................   1- 2
  25.         fread ...............................................   1- 2
  26.         fwrite ..............................................   1- 2
  27.         fmove ...............................................   1- 3
  28.         fdel ................................................   1- 3
  29.         fren ................................................   1- 3
  30.  
  31.         Sect 2: STRING MANIPULATION
  32.  
  33.         strlen ..............................................   2- 1
  34.         strcmp ..............................................   2- 1
  35.         strcopy .............................................   2- 1
  36.         strcat ..............................................   2- 1
  37.  
  38.         Sect 3: SCREEN I/O
  39.  
  40.         atputs ..............................................   3- 1
  41.         atputc ..............................................   3- 1
  42.         cls .................................................   3- 2
  43.         cur_on ..............................................   3- 2
  44.         cur_off .............................................   3- 2
  45.         set_cur .............................................   3- 2
  46.         set_mode ............................................   3- 3
  47.         set_page ............................................   3- 3
  48.         scrl_up .............................................   3- 3
  49.         scrl_dwn ............................................   3- 3
  50.  
  51.         Sect 4: KEYBOARD I/O
  52.  
  53.         getc ................................................   4- 1
  54.         getcwt ..............................................   4- 1
  55.         getcraw .............................................   4- 1
  56.  
  57.         Sect 5: CONVERSIONS
  58.  
  59.         atoi ...............................................    5- 1
  60.         itoa ...............................................    5- 1
  61.  
  62.         Sect 6: SOUND
  63.  
  64.         sound ..............................................    6- 1
  65.  
  66.         Sect 7: EDINPUT
  67.  
  68.         keygets ............................................    7- 1
  69.  
  70.         FILE I/O                                                1- 1
  71.  
  72.  
  73.        FCREATE creates a file of specified name and attribute
  74.                 or truncates an existing file for write operations.
  75.  
  76.         USAGE:  channel= fcreate(name, att);
  77.  
  78.         RETURN:         0= error       !0= channel
  79.  
  80.         ATTRIBUTE:      Note that there are defined symbols for the
  81.                 attribute of the file.  These are
  82.  
  83.                 FC$NORM  = normal file
  84.                 FC$RD_O  = read only
  85.                 FC$HID   = hidden
  86.                 FC$SYS   = system
  87.  
  88.                 F$NORM must be used alone, the others can be combined.
  89.  
  90.  
  91.        FOPEN opens an existing file for read, write or both I/O
  92.               operations.
  93.  
  94.         USAGE:  channel= fopen(name, access)
  95.  
  96.         RETURN:         0= error        !0= channel
  97.  
  98.         ACCES:          Note that there are defined symbols for the
  99.                 acces of the file.  These are
  100.  
  101.                 FO$READ  = read from file only
  102.                 FO$WRTE  = write to file only
  103.                 FO$UPDT  = allow both reading from and writing to file
  104.  
  105.                 These must be used seperately.
  106.  
  107.         FILE I/O                                                        1- 2
  108.  
  109.  
  110.        FCLOSE closes the file which was fopen'd or fcreate'd.
  111.  
  112.         USAGE:  status=  fclose(channel);
  113.  
  114.         RETURN:         0= Success      !0= Error
  115.  
  116.  
  117.        FREAD reads a number of bytes from a fopen'd file.
  118.  
  119.         USAGE:  bytesread= fread(channel, buffer, count);
  120.  
  121.         RETURN:         number of bytes read.
  122.  
  123.         NOTE:   If the number of bytes read = 0, you have EOF.
  124.                 If the number of bytes read != count, there may be an error.
  125.  
  126.  
  127.        FWRITE write a number of bytes to a fopen'd or fcreate'd file.
  128.  
  129.         USAGE:  byteswritten= fwrite(channel, buffer, count);
  130.  
  131.         RETURN:         number of bytes read.
  132.  
  133.         NOTE:   If the number of bytes written != count, you probably
  134.                 have run out of disk space and should be considered
  135.                 an error.
  136.  
  137.  
  138.     **  NOTE:   There are 3 file channels which are defined and do not need
  139.                 to be opened before read or written to.  These are
  140.  
  141.                 STDIN           standard input
  142.                 STDOUT          standard output
  143.                 STDERR          standard error
  144.  
  145.         FILE I/O                                                        1- 3
  146.  
  147.  
  148.        FMOVE changes the position of the file pointer within a file.
  149.  
  150.         USAGE:  status= fmove(channel, long displacement, baserel);
  151.  
  152.         RETURN:         0= Successful   !0= Error
  153.  
  154.         DISPLACEMENT:   Note the displacement is a 32 bit unsigned integer.
  155.  
  156.         BASEREL:        Note, The move is relative to a base.  There are
  157.                         three defined symbols for the base which are
  158.  
  159.                 FM$BOF   Beginning of file + displacement
  160.                 FM$CUR   Current position in file + displacement
  161.                 FM$EOF   End of file + displacement
  162.  
  163.                 None of these can be used together.
  164.  
  165.  
  166.        FDEL deletes a named file from secondary storage, disk drives.
  167.  
  168.         USAGE:  status= fdel(name);
  169.  
  170.         RETURN:         0= Success      !0= Error
  171.  
  172.  
  173.        FREN renames a file across directories but not across devices.
  174.  
  175.         USAGE:  status= fren(to, from);
  176.  
  177.         RETURN:         0= Success      !0= Error
  178.  
  179.         STRING MANIPULATION                                             2- 1
  180.  
  181.  
  182.        STRLEN returns the length of a string, not counting 0 terminater.
  183.  
  184.         USAGE:  length= strlen(string);
  185.  
  186.         RETURN:         length of string.
  187.  
  188.  
  189.        STRCPY copies one string into another.
  190.  
  191.         USAGE:  strcpy(to, from);
  192.  
  193.         RETURN:         nothing
  194.  
  195.  
  196.        STRCAT concatenates one string to the end of another.
  197.  
  198.         USAGE:  strcat(to, from);
  199.  
  200.         RETURN:         nothing
  201.  
  202.  
  203.        STRCMP compares one string with another.
  204.  
  205.         USAGE:  flag= strcmp(string1, string2);
  206.  
  207.         RETURN:         -?=     string1 < string2
  208.                          0=     string1 = string2
  209.                          ?=     string1 > string2
  210.  
  211.         SCREEN I/O                                                      3- 1
  212.  
  213.  
  214.        ATPUTS puts a line to the screen with specified attribute and page.
  215.  
  216.         USAGE:  atputs(string, page, row, col, attr);
  217.  
  218.         RETURN:         nothing
  219.  
  220.         PAGE:   This is for screen modes 2 & 3, BW or COLOR 80X25.
  221.                 Valid values are 0 - 3.
  222.  
  223.         ROW & COLUMN:   Where to place the string on the screen.
  224.  
  225.         ATTRIBUTE:      The attribute of the characters on the screen.
  226.  
  227.                 ---------------------------------
  228.                 : 7 : 6 : 5 : 4 : 3 : 2 : 1 : 0 :
  229.                 ---------------------------------    Foreground Color
  230.                   |   |   |   |   |   |   |   +--->     BLUE
  231.                   |   |   |   |   |   |   +------->     GREEN
  232.                   |   |   |   |   |   +----------->     RED
  233.                   |   |   |   |   +--------------->     INTENSITY
  234.                   |   |   |   +------------------->     BLUE
  235.                   |   |   +----------------------->     GREEN
  236.                   |   +--------------------------->     RED
  237.                   +------------------------------->     BLINKING
  238.  
  239.  
  240.        ATPUTC puts a character to the screen with attribute and page.
  241.  
  242.         USAGE:  atputc('a', page, row, col, attr);
  243.  
  244.         RETURN:         nothing
  245.  
  246.     **  SEE ATPUTS for more information.
  247.  
  248.         SCREEN I/O                                                      3- 2
  249.  
  250.  
  251.        CLS clears the screen and homes the cursor of the given screen page
  252.             if not in graphics mode.
  253.  
  254.         USAGE:  CLS(page)
  255.  
  256.         RETURN:         nothing
  257.  
  258.  
  259.  
  260.        CUR_ON causes the cursor to be seen.
  261.  
  262.         USAGE:  CUR_ON()
  263.  
  264.         RETURN:         nothing
  265.  
  266.  
  267.  
  268.        CUR_OFF causes the video controller to stop displaying the cursor.
  269.  
  270.         USAGE:  CUR_OFF()
  271.  
  272.         RETURN:         nothing
  273.  
  274.         NOTE:   CLS will turn the cursor back on as might other screen I/O.
  275.  
  276.  
  277.  
  278.        SET_CUR sets the position of the cursor on the screen.
  279.  
  280.         USAGE:  set_cur(row, col, page);
  281.  
  282.         RETURN:         nothing
  283.  
  284.         SCREEN I/O                                                      3- 3
  285.  
  286.  
  287.  
  288.  
  289.        SET_MODE sets the mode of the video controller.
  290.  
  291.         USAGE:  set_mode(mode);
  292.  
  293.         RETURN:         nothing
  294.  
  295.    ***  NOTE:   There are 7 symbols defined in SCREEN.H for C programs
  296.                 to be used with this function.  The 7 modes are
  297.  
  298.         SYMBOL          MODE                            PAGES
  299.         ------          ----                            -----
  300.         SM$40BW         40X25 Black and White           0 - 7
  301.         SM$40CL         40X25 Color                     0 - 7
  302.         SM$80BW         80X25 Black and White           0 - 3
  303.         SM$80CL         80X25 Color                     0 - 3
  304.         SM$320CL        320X200 Color                     0
  305.         SM$320BW        320X200 Black and White           0
  306.         SM$640BW        640X200 Black and White           0
  307.  
  308.                 The graphics modes have only one page.
  309.  
  310.  
  311.  
  312.        SET_PAGE sets the currently displayed screen page.
  313.  
  314.         USAGE:  set_page(page);
  315.  
  316.         RETURN:         nothing
  317.  
  318.     **  NOTE:   See SET_MODE for more information about pages.
  319.  
  320.  
  321.        SCRL_UP scrolls the window mapped by an upper left point
  322.                 and a lower right point a specified number of lines.
  323.  
  324.         USAGE:  scrl_up(no_lines, urow, ucol, lrow, lcol, attr);
  325.  
  326.         RETURN:         nothing
  327.  
  328.     **  NOTE:   If the number of lines specified is zero (0), The whole
  329.                 window is cleared.  This is how CLS works.  The attribute
  330.                 is the attribute of the blanks of the erased lines
  331.  
  332.  
  333.  
  334.        SCRL_DWN scrolls the window mapped by an upper left point
  335.                 and a lower right point a specified number of lines.
  336.  
  337.         USAGE   scrl_dwn(no_lines, urow, ucol, lrow, lcol, attr);
  338.  
  339.         RETURN:         nothing
  340.  
  341.         NOTE:   See SCRL_UP for more information.
  342.  
  343.         KEYBOARD I/O                                                    4- 1
  344.  
  345.  
  346.  
  347.        GETC gets a character from the keyboard if available.
  348.  
  349.         USAGE:  char= getc();
  350.  
  351.         RETURN:         0= character available  ?= character from keyboard.
  352.  
  353.         NOTE:   These functions convert special characters to predefined
  354.                 symbols which can be used by including KEYBOARD.H.
  355.  
  356.  
  357.  
  358.  
  359.        GETCW waits for a character to be typed before returning.
  360.  
  361.         USAGE:  char= getcw();
  362.  
  363.         RETURN:         a character
  364.  
  365.         NOTE:   See GETC note for more information.
  366.  
  367.  
  368.  
  369.        GETCRAW waits for a character to be typed before returning
  370.                 the unconverted character in integer form.
  371.  
  372.         USAGE:  int     rawchr;
  373.                 rawchr= getcraw();
  374.  
  375.         NOTE:   The high 8 bits is the scan code and the low 8 bits is
  376.                 the character
  377.  
  378.  
  379.    **   NOTE:   The following are symbols defined by key.h .
  380.  
  381.                 LFTCH   RGTCH   INS     DEL     F1      F2      F3
  382.                 F4      F5      F6      F7      F8      F9      F10
  383.                 BOL     EOL     PGUP    PGDWN   PRVWRD  NEXWRD
  384.  
  385.         CONVERSIONS                                                     5- 1
  386.  
  387.  
  388.        ATOI converts an ASCII string of specified base to an integer.
  389.  
  390.         USAGE:  err= atoi(string, &integer, base);
  391.  
  392.         RETURN:         0= Error        1= Success
  393.  
  394.         NOTE:   This function is limited by INTEGER size.  If a string
  395.                 has a value more than 65535, your result is meaningless.
  396.                 Also, an error signifies an invalid digit for the specified
  397.                 base was found.
  398.  
  399.  
  400.  
  401.  
  402.        ITOA converts an integer to a string of the specified base.
  403.  
  404.         USAGE:  itoa(string, integer, base);
  405.  
  406.         RETURN:         nothing
  407.  
  408.         NOTE:   This command will treat the integer as unsigned.
  409.  
  410.         SOUND                                                           6- 1
  411.  
  412.  
  413.        SOUND will generate a frequency for a specified duration
  414.  
  415.         USAGE:  sound(freq, dur);
  416.  
  417.         RETURNS:        nothing but sound
  418.  
  419.         NOTE:   The duration is in hundredths (.01) of a second.
  420.  
  421.         FREQUENCY CHART
  422.  
  423.                        NOTE              FREQUENCY
  424.                         C               130.8   131
  425.                         C#              138.6   139
  426.                         D               146.8   147
  427.                         D#              155.6   156
  428.                         E               164.9   165
  429.                         F               174.6   175
  430.                         F#              185.0   185
  431.                         G               196.0   196
  432.                         G#              207.7   208
  433.                         A               220.0   220
  434.                         A#              233.1   233
  435.                         B               246.9   247
  436.                  MIDDLE C               261.7   262
  437.                         C#              277.2   277
  438.                         D               293.7   294
  439.                         D#              311.1   311
  440.                         E               329.6   330
  441.                         F               349.2   349
  442.                         F#              370.0   370
  443.                         G               392.0   392
  444.                         G#              415.3   415
  445.                         A               440.0   440
  446.                         B               493.9   494
  447.                         C               523.3   523
  448.  
  449.         EDINPUT                                                         7- 1
  450.  
  451.  
  452.  
  453.  
  454.        KEYGETS will get edited input from the keyboard.
  455.  
  456.         USAGE:  keygets(string, length, row, col, page, upper);
  457.  
  458.         RETURNS:        nothing
  459.  
  460.         NOTE(S):        The passed in string should either be set
  461.                 to all spaces or some predefined value before calling.
  462.  
  463.                         The variable upper is a boolean on whether
  464.                 the input should be converted to upper case.
  465.